# 02 - 技术栈与架构总览

## 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| **运行时** | Bun | 替代 Node.js，更快的启动和执行 |
| **语言** | TypeScript (strict) | 严格模式类型检查 |
| **终端 UI** | React + 自定义 Ink 渲染器 | 不是 npm 上的 Ink 库，而是项目内嵌的深度定制版本 |
| **CLI 框架** | Commander.js | 命令行参数解析 |
| **校验** | Zod v4 | 运行时 schema 校验（Tool 输入/输出、配置） |
| **AI API** | @anthropic-ai/sdk | Claude API 调用 |
| **外部协议** | MCP (Model Context Protocol) | 扩展工具能力 |
| **语言服务** | LSP (Language Server Protocol) | 代码智能感知 |
| **认证** | OAuth 2.0 + JWT + Keychain | 多层认证方案 |
| **构建** | Bun bundler + feature flags | 编译时特性开关，死代码消除 |

---

## Feature Flags 机制

这是项目的一个重要特性。通过 `bun:bundle` 的 `feature()` 函数实现**编译时**特性开关：

```typescript
import { feature } from 'bun:bundle'

// 编译时决定：如果 COORDINATOR_MODE 为 false，
// 下面的 require 和相关代码会被完全移除
const coordinatorModeModule = feature('COORDINATOR_MODE')
  ? require('./coordinator/coordinatorMode.js')
  : null
```

已知的 Feature Flags 包括：
- `COORDINATOR_MODE` — 多 Agent 协调器
- `VOICE_MODE` — 语音输入
- `PROACTIVE` — 主动模式
- `AGENT_TRIGGERS` — 定时触发器
- `AGENT_TRIGGERS_REMOTE` — 远程触发器
- `REACTIVE_COMPACT` — 响应式压缩
- `CONTEXT_COLLAPSE` — 上下文折叠
- `WEB_BROWSER_TOOL` — 网页浏览工具
- `HISTORY_SNIP` — 历史裁剪
- `WORKFLOW_SCRIPTS` — 工作流脚本
- `KAIROS` — 推送通知等高级功能

---

## 整体架构图

```
┌─────────────────────────────────────────────────────┐
│                     用户界面层                        │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │ 终端 CLI │  │ IDE 桥接  │  │  SDK / Server     │  │
│  │(main.tsx)│  │ (bridge/) │  │ (entrypoints/)    │  │
│  └────┬─────┘  └────┬─────┘  └───────┬───────────┘  │
│       │              │                │              │
│       └──────────────┼────────────────┘              │
│                      ▼                               │
│  ┌─────────────────────────────────────────────────┐ │
│  │            QueryEngine（会话引擎）                │ │
│  │  - 会话生命周期管理                               │ │
│  │  - 消息历史维护                                   │ │
│  │  - 系统提示构建                                   │ │
│  │  - 自动压缩 (compact)                            │ │
│  └─────────────────────┬───────────────────────────┘ │
│                        ▼                             │
│  ┌─────────────────────────────────────────────────┐ │
│  │              query.ts（单轮执行器）               │ │
│  │  - API 流式调用                                   │ │
│  │  - Tool 调度与并发控制                            │ │
│  │  - 中断处理                                       │ │
│  └────────┬────────────────────────┬───────────────┘ │
│           ▼                        ▼                 │
│  ┌────────────────┐   ┌──────────────────────────┐   │
│  │  Anthropic API │   │     Tool 系统             │   │
│  │  (流式 SSE)    │   │  ┌──────────────────────┐│   │
│  └────────────────┘   │  │ 权限检查              ││   │
│                       │  │ validateInput()       ││   │
│                       │  │ checkPermissions()    ││   │
│                       │  │ call()                ││   │
│                       │  └──────────────────────┘│   │
│                       │  40+ 具体 Tool 实现       │   │
│                       └──────────────────────────┘   │
│                                                      │
│  ┌─────────────────────────────────────────────────┐ │
│  │                  服务层                           │ │
│  │  API | MCP | OAuth | LSP | Analytics | Compact   │ │
│  └─────────────────────────────────────────────────┘ │
│                                                      │
│  ┌─────────────────────────────────────────────────┐ │
│  │              状态 & 配置                          │ │
│  │  AppState | 设置 | 记忆 | 文件状态缓存            │ │
│  └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
```

---

## 三种使用模式

| 模式 | 入口 | 说明 |
|------|------|------|
| **REPL 模式** | `main.tsx` → React UI | 用户在终端交互式对话 |
| **Print 模式** | `main.tsx --print` | 单次查询，输出结果后退出 |
| **SDK 模式** | `entrypoints/` | 作为库被其他程序调用 |

IDE 桥接（Bridge）模式可以与上述任意模式配合，通过 WebSocket 与 VS Code / JetBrains 扩展通信。

---

## 数据流概要

```
1. 用户输入文本或斜杠命令
       │
2. processUserInput() 解析
       │
       ├─ 斜杠命令 → commands.ts 分发 → 命令执行
       │
       └─ 普通文本 → QueryEngine.submit()
              │
3. 构建系统提示 (system prompt)
   - 基础指令 + Tool 描述 + 上下文 + CLAUDE.md 记忆
              │
4. 发送到 Anthropic API（流式）
              │
5. 接收响应流
   - 文本 → 直接渲染到终端
   - tool_use → 进入 Tool 调度
              │
6. Tool 调度
   ├─ validateInput() 校验输入
   ├─ checkPermissions() 权限检查
   │    ├─ allow → 直接执行
   │    ├─ deny → 返回错误
   │    └─ ask → 弹出用户确认
   └─ call() 执行 Tool
              │
7. Tool 结果 → 构建新消息 → 回到步骤 4（循环）
              │
8. 模型输出 end_turn → 本轮结束，等待下一次用户输入
```

> **关键循环**: 步骤 4-7 形成 **agentic loop**（代理循环），Claude 可以连续调用多个 Tool 直到完成任务。这是 Claude Code 作为 Agent 的核心机制。